Build congressional districts for US state runs only - #955

Fixes #954

Same-Repository Draft PR Check

• This PR is a draft.
• This PR is from a branch in PolicyEngine/policyengine-sim-api, not a personal fork.

Do not merge yet

Merging to main deploys staging and then production. Until PolicyEngine/policyengine-app-v2#1439 is released, the app reads congressional districts from nationwide results, so this may merge only after that release has been in production for at least a day.

That app release in turn waits for the Public API's PolicyEngine/policyengine-api#4064 and this repository's #940 to deploy.

Summary

Why:

• A US national run computes congressional district impacts from the national dataset. A state run computes them from its own state dataset. So the same district shows different figures in a nationwide report and in its state's report.
• With Nationwide congressional districts from state runs, in v3 and v2 policyengine-app-v2#1439, nationwide reports take each district from a separate run of its state (and DC) on that state's dataset instead. National runs no longer need to compute districts.
• A search of PolicyEngine's repositories found no other reader of nationwide districts. The Public API passes the field through unchanged.

What changes:

• _should_build_us_congressional_district_impact (simulation_output_geographic.py) now returns true only for a state/* region, in any case.
• Computes no districts (congressional_district_impact is null in the output, and the gateway's job-status response, sent with response_model_exclude_none=True, leaves the field out):
  • national runs, with no region or us;
  • region-group runs, which include the children of a segmented national run;
  • the segmented national reduce and Stage 12 aggregation of a national report, which build their output with the national region;
  • district and place runs, as before.
• Still computes districts: a state run, and Stage 12 aggregation of a state report, which passes on that state's region as the request spelled it, so only a state/... spelling matches there (a bare ut computes none on that path, as before this change; the Public API always sends state/...).
• The contract field is already nullable, so the schema and the generated clients are unchanged.
• Docstrings updated in simulation_output_geographic.py and segmented_national_reduce.py, and a changelog entry.
• Integration checks:
  • a new helper, assert_no_congressional_district_results, checks that the field is absent or null;
  • test_calculate_default_model, a US national run, uses it in place of the at-large district check;
  • the Utah state check still expects UT- districts, and the pinned-version check now runs Vermont and expects exactly VT-01.
• _AT_LARGE_DISTRICT_IDS served only the national check, so it is removed. assert_congressional_district_results' expected_district_ids option, which also served only that check, now matches a state's district IDs exactly (item 5 below).

Older model versions: a deployment rebuilds only the Modal app for the current policyengine.py version. Apps already deployed for older versions are not rebuilt and keep their code, so a request pinned to an older model version can still return nationwide districts.

Testing

Each commit is red-green: the tests were written first and run before the code change.

1. Build congressional districts for state runs only
   • Seen failing first:
     • TestCongressionalDistrictRegions::test__rejects_national_and_group (None, us, region_group/…);
     • test_builder_skips_districts_for_national_and_region_group_runs for None, us and a region group, because the output builder still ran the district calculation.
   • Passed before and after:
     • test__allows_states (state/ca, STATE/CA);
     • test__rejects_district_and_place;
     • test_builder_builds_districts_for_state_runs (state/ut).
2. Expect no congressional districts on a US national integration result
   • Seen failing first, because the helper did not exist: its local tests, which accept a null field in a dict or a generated client object, and refuse an empty district list, a listed district and a generated client object with districts.
3. Say which Stage 12 reports still compute congressional districts
   • Documentation only: the check's docstring and the changelog item now say "Stage 12 aggregation of a national report", so there is no failing-test step.
4. Accept a national result without the district field (review round 1)
   • The helper first required the field to be present, which a deployed result never has, so the beta check would have failed after deploy and stopped the production deploy. test_national_us_assertions_accept_a_result_without_districts now also passes a dict and a generated client object without the field; it failed with "Missing 'congressional_district_impact'" before the helper was changed to .get(...) is None, as assert_no_uk_area_results already does. The test that refused a result without the field is removed.
5. Check an at-large state's one district in beta (review round 2)
   • Removing the national check left no deployed check of an at-large state, and the two Utah beta tests sent the same request. test_calculate_specific_model now runs state/vt and expects exactly VT-01, through assert_congressional_district_results' expected_district_ids option, which main has as a subset check for the national result: an earlier commit here removed it with that check, and this one restores it as an exact match of the sorted IDs, so a district listed twice fails too (review round 3). Its local tests (test_state_assertions_accept_an_at_large_state_with_its_one_district, test_state_assertions_reject_other_district_ids) failed first, because the option did not exist on this branch and then because a repeated district passed. The beta suite keeps the same number of tests.

Run locally:

• uv run --frozen pytest tests/ in projects/policyengine-simulation-executor: 1881 passed, 22 skipped.
• uv run --frozen pytest tests/simulation/test_calculate.py -m "not beta_only" in projects/policyengine-apis-integ: 23 passed (before the review rounds, which removed one of these tests and added two).
• make check: Ruff format and lint, and Pyright for every package, passed.
• GITHUB_BASE_REF=main python scripts/run_quality_guards.py: every guard passed.
• After review round 1: the district helper's local tests by node ID (4 cases) passed, with Ruff on the changed files and BASE_SHA=origin/main .github/scripts/check-changelog-fragment.sh.

Not run locally: the beta_only integration tests, which run against the beta deployment. The national check runs on the app that beta's latest route points to, and latest moves only to a newer policyengine.py version (or when forced): if a branch with a newer version and without this change were deployed to beta by hand, that check would fail, and stop the production deploy, until latest points to an app with this change. After this deploys to beta, a US national result from the current version's app should have no congressional_district_impact field, and a state/ut result should still list UT- districts. The null check applies only to the current version's app, for the reason under "Older model versions".

🤖 Generated with Claude Code